[WIP]: Create a Plugin System for Lima #3573

unsuman · 2025-05-23T16:09:16Z

Important

This PR is only for preview purposes and not meant to be merged. Later, the commits can be cherry-picked and raised as separate small PRs.

This PR creates a Plugin System for drivers which can be embedded in the main binary or built as separate binaries, which then communicate with the main binary using gRPC. This work is done as part of my GSoC '25 task.

AkihiroSuda · 2025-05-26T05:33:16Z

cmd/limactl/start.go

@@ -54,6 +56,9 @@ $ limactl create --set='.cpus = 2 | .memory = "2GiB"'
 To see the template list:
 $ limactl create --list-templates

+To see the drivers list:
+$ limactl create --list-drivers


The example currently just focuses on templates, not on drivers.

cmd/limactl/disk.go

pkg/builtins/drivers.go

pkg/driver/driver.go

pkg/driver/vz/vz_driver_darwin.go

AkihiroSuda · 2025-05-26T05:39:06Z

pkg/driver/vz/vz_driver_others.go

@@ -0,0 +1,118 @@
+//go:build !darwin || no_vz


The package shouldn't be compiled at all on non-Darwin

Signed-off-by: Ansuman Sahoo <[email protected]>

…plugin related functions Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

…rnal drivers Signed-off-by: Ansuman Sahoo <[email protected]>

…internal plugins Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

…rface Signed-off-by: Ansuman Sahoo <[email protected]>

…ement common error Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

…function Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

AkihiroSuda · 2025-06-04T05:41:59Z

pkg/driver/external/client/methods.go

+func (d *DriverClient) Initialize(ctx context.Context) error {
+	d.logger.Debug("Initializing driver instance")
+
+	connCtx, cancel := context.WithTimeout(ctx, 5*time.Second)


timeout should be specified in the caller

AkihiroSuda · 2025-06-04T05:42:21Z

pkg/driver/external/server/methods.go

+	for {
+		n, err := conn.Read(buf)
+		if err != nil {
+			if err == io.EOF {


errors.Is is more robust

…ocess Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

…in SetConfig() Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

AkihiroSuda · 2025-06-11T05:54:52Z

pkg/driver/qemu/cmd/main.go

This should be cmd/<EXECUTABLE NAME>/main.go

Makefile has to be updated to compile this by default.

AkihiroSuda · 2025-06-11T06:03:17Z

How to test this ?

Tried go build -o ~/.local/libexec/lima/drivers/lima-driver-qemu ./pkg/driver/qemu/cmd , but ~/.local/bin/limactl did not recognize the driver.

unsuman · 2025-06-11T08:08:48Z

How to test this ?

Tried go build -o ~/.local/libexec/lima/drivers/lima-driver-qemu ./pkg/driver/qemu/cmd , but ~/.local/bin/limactl did not recognize the driver.

The driver discovery through the directory is not working rn. I will work on it once I fix the GuestAgentConn() function.

For now, you can test the driver by setting the executable driver's path to LIMA_DRIVERS_PATH

Signed-off-by: Ansuman Sahoo <[email protected]>

…socket Signed-off-by: Ansuman Sahoo <[email protected]>

Signed-off-by: Ansuman Sahoo <[email protected]>

jandubois · 2025-06-19T22:33:02Z

cmd/limactl/main_darwin.go

@@ -0,0 +1,9 @@
+//go:build darwin && !no_vz


I like to avoid double-negation, when possible:

Suggested change

//go:build darwin && !no_vz

//go:build darwin && driver_vz

Then the Makefile will just have a DRIVER_TAGS=driver_qemu,driver_vz,driver_wsl setting that the user can override to only include the desired driver(s).

Also go:build darwin is already implied by the filename

jandubois · 2025-06-19T22:38:05Z

pkg/driver/driver.go

-func (d *BaseDriver) Stop(_ context.Context) error {
-	return nil
+	ChangeDisplayPassword(ctx context.Context, password string) error
+	GetDisplayConnection(ctx context.Context) (string, error)


In Go "getters" don't use a Get prefix. You know it is a getter because the method name doesn't include an action word (verb).

Suggested change

GetDisplayConnection(ctx context.Context) (string, error)

DisplayConnection(ctx context.Context) (string, error)

jandubois · 2025-06-19T22:42:30Z

pkg/driver/driver.go

-func (d *BaseDriver) ApplySnapshot(_ context.Context, _ string) error {
-	return errors.New("unimplemented")
-}
+	GetInfo() Info


I'm not going to comment on additional setters; they all should drop the Get prefix.

Suggested change

GetInfo() Info

Info() Info

jandubois · 2025-06-19T22:51:18Z

pkg/driver/driver.go

-func (d *BaseDriver) DeleteSnapshot(_ context.Context, _ string) error {
-	return errors.New("unimplemented")
+	// SetConfig sets the configuration for the instance.
+	SetConfig(inst *store.Instance, sshLocalPort int)


I wonder if it makes sense to have a separate type (like the Kubernetes Completed* types):

type ConfiguredDriver struct { Driver }

Then you could have a function to turn a Driver into a ConfiguredDriver:

Suggested change

SetConfig(inst *store.Instance, sshLocalPort int)

Configure(inst *store.Instance, sshLocalPort int) ConfiguredDriver

And all the functions/methods that would only work with configured driver would only accept that type instead.

pkg/driver/external/server/server.go

jandubois · 2025-06-19T23:07:43Z

pkg/driver/qemu/cmd/lima-driver-qemu/main.go

I think it would be better to move this to cmd/lima-driver-qemu at the top level. There should be no main packages with a main function inside the pkg tree.

jandubois · 2025-06-19T23:16:53Z

pkg/driver/qemu/qemu_driver.go

+	VSockPort    int
+	VirtioPort   string
+
+	DriverType driver.DriverType


It feels like a failure of the abstraction if the driver needs to know if it is an internal or external driver. I was hoping that this could be entirely handled by the remoting layer.

GuestAgentConn needs to know this, at least for now

I see this now. I hope we can fix this.

One way to deal with this would be to have both a GuestAgentConn() and ExternalGuestAgentConn() method on the driver, and the driverserver.GuestAgentConn() method in pkg/driver/external/server/methods.go would call s.driver.ExternalGuestAgentConn() instead of the internal version.

Maybe call it GuestAgentConnExternal() so both have the same prefix, idk.

jandubois

Sorry, my earlier feedback from today was supposed to be part of this, but I continued to press the wrong button.

jandubois · 2025-06-19T23:26:09Z

pkg/driver/vz/cmd/lima-driver-vz/main.go

@@ -0,0 +1,18 @@
+//go:build (darwin && amd64) || (darwin && arm64)


Why is this not just checking for darwin?

Suggested change

//go:build (darwin && amd64) || (darwin && arm64)

//go:build darwin

jandubois · 2025-06-19T23:33:15Z

pkg/driver/vz/disk.go

There is some inconsistency in the go:build line between the files in this directory. E.g. errors_darwin.go has

/go:build darwin && !no_vz

It looks like including/excluding the driver is controlled by importing pkg/driver/vz/register into main, so that file is really the only one that needs the go:build line. All the rest are not referenced and don't need it.

If we want to keep it for some kind of "belts & suspender" reasons, then all the files should have it.

I also think that we should rename all the file to remove the _darwin suffix from the filenames. It is no longer needed because the files will not be referenced on any other OS. Only the _arm64 suffix on the Rosetta code needs to stay.

It is no longer needed because the files will not be referenced on any other OS.

Still needed to allow running golangci-lint run ./..., govulncheck ./..., etc. on non-macOS ?

Still needed to allow running golangci-lint run ./..., govulncheck ./..., etc. on non-macOS ?

Yeah, probably true. But then it can be removed from the go:build line.

jandubois · 2025-06-19T23:50:33Z

pkg/driverutil/instance.go

-	if *limaDriver == limayaml.WSL2 {
-		return wsl2.New(base)
+// CreateTargetDriverInstance creates the appropriate driver for an instance.
+func CreateTargetDriverInstance(inst *store.Instance, sshLocalPort int) (driver.Driver, error) {


We are overloading the word instance here, for drivers and machines.

I think my previous suggestion to use a different type for DriverInstance would work well here:

Suggested change

func CreateTargetDriverInstance(inst *store.Instance, sshLocalPort int) (driver.Driver, error) {

func CreateConfiguredDriver(inst *store.Instance, sshLocalPort int) (driver.ConfiguredDriver, error) {

jandubois · 2025-06-19T23:51:51Z

pkg/driverutil/instance.go

+	driver.SetConfig(inst, sshLocalPort)
+
+	return driver, nil


Suggested change

driver.SetConfig(inst, sshLocalPort)

return driver, nil

return driver.Configure(inst, sshLocalPort)

pkg/driver/external/server/server.go

jandubois · 2025-06-20T01:05:02Z

pkg/registry/registry.go

+	if err != nil {
+		return err
+	}
+	stdDriverDir := filepath.Join(homeDir, ".local", "libexec", "lima", "drivers")


I thought this was going to be /usr/local/libexec/lima and not a user-owned directory. We don't store anything except LIMA_HOME under the user's home directory.

jandubois · 2025-06-20T01:06:50Z

pkg/registry/registry.go

+
+			info, err := os.Stat(path)
+			if err != nil {
+				logrus.Warnf("Error accessing driver path %s: %v", path, err)


For consistency we should always quote filenames. Especially if they are user-provided and may contain whitespace. But let's just always do it:

Suggested change

logrus.Warnf("Error accessing driver path %s: %v", path, err)

logrus.Warnf("Error accessing driver path %q: %v", path, err)

jandubois · 2025-06-20T01:12:55Z

pkg/registry/registry.go

+func (r *Registry) registerDriverFile(path string) {
+	base := filepath.Base(path)
+	if !strings.HasPrefix(base, "lima-driver-") {
+		fmt.Printf("Skipping %s: does not start with 'lima-driver-'\n", base)


I assume this is debugging code; we don't want to print anything for ignored files.

jandubois · 2025-06-20T01:15:06Z

pkg/registry/registry.go

+	}
+
+	name := strings.TrimPrefix(base, "lima-driver-")
+	name = strings.TrimSuffix(name, filepath.Ext(name))


I guess this is fine; we don't need to allow . in driver names. Otherwise I would have said we only strip .exe suffix on Windows, but otherwise allow any characters.

jandubois · 2025-06-20T01:23:07Z

pkg/store/instance.go

+	errorsAsStrings := make([]string, len(inst.Errors))
+	for i, err := range inst.Errors {
+		if err != nil {
+			errorsAsStrings[i] = err.Error()
+		}
+	}


I don't know if this is going to work properly. E.g. if the error is later processed again with errors.Is(), then the result will always be false because we are not preserving the type.

Not sure if that is important, but it would require some reflection magic to make it work.

AkihiroSuda added the gsoc/2025 Google Summer of Code 2025 label May 23, 2025

unsuman force-pushed the feature/driver-plugin-system branch from 77877e0 to 7a082d2 Compare May 25, 2025 11:21